[ES|QL] Add MATCH_PHRASE #127661

kderusso · 2025-05-02T19:50:40Z

Adds MATCH_PHRASE support to ES|QL.

Some examples of how to use MATCH_PHRASE:

POST _query?format=txt
{
  "query": """
  FROM books METADATA _score
  | WHERE MATCH_PHRASE(title, "return of the king")
  | KEEP title, _score
  | SORT _score
  | LIMIT 5
  """
}

POST _query?format=txt
{
  "query": """
  FROM books METADATA _score
  | WHERE MATCH_PHRASE(title, "return of king", {"slop": 5})
  | KEEP title, _score
  | SORT _score
  | LIMIT 5
  """
}

POST _query?format=txt
{
  "query": """
  FROM books METADATA _score
  | WHERE MATCH_PHRASE(title, "return of king", {"analyzer": "whitespace"})
  | KEEP title, _score
  | SORT _score
  | LIMIT 5
  """
}

POST _query?format=txt
{
  "query": """
  FROM books METADATA _score
  | WHERE MATCH_PHRASE(title, "", {"zero_terms_query": "all"})
  | KEEP title, _score
  | SORT _score
  | LIMIT 5
  """
}

elasticsearchmachine · 2025-05-07T18:16:42Z

Hi @kderusso, I've created a changelog YAML for you.

…t only

kderusso · 2025-05-09T19:46:05Z

...sql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java

+
+            MatchPhrase can use <<esql-function-named-params,function named parameters>> to specify additional options for the
+            match_phrase query.
+            All <<query-dsl-match-query-phrase,match_phrase>> query parameters are supported.


Note: When I try to link to the correct doclink here, I get:

Invalid link key <<match-phrase-field-params,match_phrase query parameters>>

kderusso · 2025-05-09T19:46:08Z

docs/reference/query-languages/esql/_snippets/functions/description/match_phrase.md

+
+**Description**
+
+Use `MATCH_PHRASE` to perform a [match_phrase query](/reference/query-languages/query-dsl/query-dsl-match-query.md#query-dsl-match-query-phrase) on the specified field. Using `MATCH_PHRASE` is equivalent to using the `match_phrase` query in the Elasticsearch Query DSL.  MatchPhrase can be used on [text](/reference/elasticsearch/mapping-reference/text.md) fields, as well as other field types like keyword, boolean, or date types. MatchPhrase is not supported for [semantic_text](/reference/elasticsearch/mapping-reference/semantic-text.md) or numeric types.  MatchPhrase can use [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params) to specify additional options for the match_phrase query. All [match_phrase](/reference/query-languages/query-dsl/query-dsl-match-query.md#query-dsl-match-query-phrase) query parameters are supported.  `MATCH_PHRASE` returns true if the provided query matches the row.


I'm not sure why we're picking up match query docs in the generated documentation here, we should be picking up query-dsl-match-query-phrase.md.

elasticsearchmachine · 2025-05-09T19:49:26Z

Pinging @elastic/es-analytical-engine (Team:Analytics)

elasticsearchmachine · 2025-05-09T19:49:26Z

Pinging @elastic/search-eng (Team:SearchOrg)

elasticsearchmachine · 2025-05-09T19:49:27Z

Pinging @elastic/search-relevance (Team:Search - Relevance)

ioanatia · 2025-05-13T13:06:38Z

docs/reference/query-languages/esql/_snippets/lists/search-functions.md

@@ -1,4 +1,7 @@
 * [preview] [`KQL`](../../functions-operators/search-functions.md#esql-kql)
 * [preview] [`MATCH`](../../functions-operators/search-functions.md#esql-match)
+* [preview] [


We don't need to modify this file, because the function is just available in snapshot.
At most you can comment this one with a % as we do for the term function.

Commented out, thanks

ioanatia · 2025-05-13T13:11:23Z

docs/reference/query-languages/esql/functions-operators/search-functions.md

 :::{include} ../_snippets/functions/layout/kql.md
 :::

 :::{include} ../_snippets/functions/layout/match.md
 :::

+:::{include} ../_snippets/functions/layout/match_phrase.md


again I don't think we need this since the function is not available outside snapshots

Commented out, thanks

ioanatia

We are missing validation tests in VerifierTests for cases like:

what happens when match_phrase is used after STATS - this should fail with a validation error
what happens when we pass invalid options to match_phrase - same, we have a validation error
what happens when match_phrase receives a column as argument that is not a mapped field - again a validation error

there are other cases that we might need to test - please take a look at what we did for match in VerifierTests and add similar tests.

x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/esql/60_usage.yml

ioanatia · 2025-05-20T08:16:54Z

...sql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java

+        return new MatchPhraseQuery(source(), fieldName, queryAsObject(), matchPhraseQueryOptions());
+    }
+
+    public static String getNameFromFieldAttribute(FieldAttribute fieldAttribute) {


This is a duplicate of:

elasticsearch/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java

Lines 468 to 475 in f4b6086

public static String getNameFromFieldAttribute(FieldAttribute fieldAttribute) {

String fieldName = fieldAttribute.name();

if (fieldAttribute.field() instanceof MultiTypeEsField multiTypeEsField) {

// If we have multiple field types, we allow the query to be done, but getting the underlying field name

fieldName = multiTypeEsField.getName();

}

return fieldName;

}

Either use the Match one or move them both to another place, like FullTextFunction.

ioanatia · 2025-05-20T08:18:11Z

...sql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java

+        return fieldName;
+    }
+
+    public static FieldAttribute fieldAsFieldAttribute(Expression field) {


This is a duplicate of:

elasticsearch/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java

Lines 477 to 484 in f4b6086

public static FieldAttribute fieldAsFieldAttribute(Expression field) {

Expression fieldExpression = field;

// Field may be converted to other data type (field_name :: data_type), so we need to check the original field

if (fieldExpression instanceof AbstractConvertFunction convertFunction) {

fieldExpression = convertFunction.field();

}

return fieldExpression instanceof FieldAttribute fieldAttribute ? fieldAttribute : null;

}

Either use the Match one or move them both to another place, like FullTextFunction.

ioanatia · 2025-05-20T08:23:03Z

...sql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java

+            }
+
+            try {
+                matchPhraseQueryOptions();


the resolveOptions function could use a refactor - because most of it is duplicated in Match, MultiMatch, QueryString and here. But I am okay with doing that as a follow up.

ioanatia · 2025-05-20T08:23:48Z

...sql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/MatchPhrase.java

+                    failures.add(
+                        Failure.fail(
+                            mp.field(),
+                            "[{}] {} cannot operate on [{}], which is not a field from an index mapping",


let's get some tests for this particular case in VerifierTests

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/action/EsqlCapabilities.java

elasticsearchmachine added the v9.1.0 label May 2, 2025

github-actions bot deployed to docs-preview May 6, 2025 17:55 View deployment

kderusso added 3 commits May 6, 2025 15:31

Initial commit of match_phrase

3bcc654

Add MatchPhraseQueryTests

baee81b

First pass at CSV specs

13ccda7

kderusso force-pushed the kderusso/esql-match-phrase branch from dabef06 to 13ccda7 Compare May 6, 2025 19:32

github-actions bot deployed to docs-preview May 6, 2025 19:32 View deployment

kderusso added :SearchOrg/Relevance Label for the Search (solution/org) Relevance team >enhancement labels May 7, 2025

Update docs/changelog/127661.yaml

c8e6770

kderusso removed the :SearchOrg/Relevance Label for the Search (solution/org) Relevance team label May 7, 2025

github-actions bot deployed to docs-preview May 7, 2025 18:17 View deployment

kderusso added :Search Relevance/Search Catch all for Search Relevance :SearchOrg/Relevance Label for the Search (solution/org) Relevance team and removed :Search Relevance/Search Catch all for Search Relevance labels May 7, 2025

github-actions bot deployed to docs-preview May 8, 2025 17:24 View deployment

github-actions bot deployed to docs-preview May 8, 2025 17:32 View deployment

github-actions bot deployed to docs-preview May 8, 2025 18:16 View deployment

Refactor so MatchPhrase doesn't use all fulltext test cases, just tex…

d02864e

…t only

kderusso force-pushed the kderusso/esql-match-phrase branch from 8f01955 to d02864e Compare May 8, 2025 20:11

github-actions bot deployed to docs-preview May 8, 2025 20:12 View deployment

Fix tests

49ae77f

github-actions bot deployed to docs-preview May 8, 2025 21:01 View deployment

Merge main

9769fca

github-actions bot deployed to docs-preview May 8, 2025 21:03 View deployment

kderusso added 3 commits May 9, 2025 15:18

Add some CSV test cases

5f14d2e

Fix test

8095a28

Merge branch 'main' into kderusso/esql-match-phrase

6ff795b

github-actions bot deployed to docs-preview May 9, 2025 19:21 View deployment

kderusso commented May 9, 2025

View reviewed changes

kderusso marked this pull request as ready for review May 9, 2025 19:49

kderusso requested review from ioanatia and carlosdelest May 9, 2025 19:49

elasticsearchmachine added Team:Analytics Meta label for analytical engine team (ESQL/Aggs/Geo) Team:SearchOrg Meta label for the Search Org (Enterprise Search) Team:Search - Relevance The Search organization Search Relevance team labels May 9, 2025

kderusso requested review from afoucret and a team May 9, 2025 19:49

ioanatia reviewed May 13, 2025

View reviewed changes

Comment out MATCH_PHRASE in search-functions Markdown

641f65b

github-actions bot deployed to docs-preview May 14, 2025 14:00 View deployment

kderusso requested a review from ioanatia May 14, 2025 14:01

Merge branch 'main' into kderusso/esql-match-phrase

b0efb7b

github-actions bot deployed to docs-preview May 14, 2025 15:06 View deployment

ioanatia requested changes May 20, 2025

View reviewed changes

Minor PR feedback

c58c4a8

github-actions bot deployed to docs-preview May 20, 2025 17:14 View deployment

PR feedback - refactor/consolidate code

7f8d663

github-actions bot deployed to docs-preview May 20, 2025 17:29 View deployment

Add some more tests

e0ae889

github-actions bot deployed to docs-preview May 20, 2025 18:16 View deployment

Fix some tests

9ebdda2

github-actions bot deployed to docs-preview May 20, 2025 19:58 View deployment

[CI] Auto commit changes from spotless

45d6810

github-actions bot deployed to docs-preview May 20, 2025 20:08 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[ES|QL] Add MATCH_PHRASE #127661

[ES|QL] Add MATCH_PHRASE #127661

kderusso commented May 2, 2025 •

edited

Loading

elasticsearchmachine commented May 7, 2025

kderusso May 9, 2025

kderusso May 9, 2025

elasticsearchmachine commented May 9, 2025

elasticsearchmachine commented May 9, 2025

elasticsearchmachine commented May 9, 2025

ioanatia May 13, 2025

kderusso May 14, 2025

ioanatia May 13, 2025

kderusso May 14, 2025

ioanatia left a comment

ioanatia May 20, 2025

ioanatia May 20, 2025

ioanatia May 20, 2025

ioanatia May 20, 2025


		Description

		Use `MATCH_PHRASE` to perform a [match_phrase query](/reference/query-languages/query-dsl/query-dsl-match-query.md#query-dsl-match-query-phrase) on the specified field. Using `MATCH_PHRASE` is equivalent to using the `match_phrase` query in the Elasticsearch Query DSL. MatchPhrase can be used on [text](/reference/elasticsearch/mapping-reference/text.md) fields, as well as other field types like keyword, boolean, or date types. MatchPhrase is not supported for [semantic_text](/reference/elasticsearch/mapping-reference/semantic-text.md) or numeric types. MatchPhrase can use [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params) to specify additional options for the match_phrase query. All [match_phrase](/reference/query-languages/query-dsl/query-dsl-match-query.md#query-dsl-match-query-phrase) query parameters are supported. `MATCH_PHRASE` returns true if the provided query matches the row.

	public static String getNameFromFieldAttribute(FieldAttribute fieldAttribute) {
	String fieldName = fieldAttribute.name();
	if (fieldAttribute.field() instanceof MultiTypeEsField multiTypeEsField) {
	// If we have multiple field types, we allow the query to be done, but getting the underlying field name
	fieldName = multiTypeEsField.getName();
	}
	return fieldName;
	}

	public static FieldAttribute fieldAsFieldAttribute(Expression field) {
	Expression fieldExpression = field;
	// Field may be converted to other data type (field_name :: data_type), so we need to check the original field
	if (fieldExpression instanceof AbstractConvertFunction convertFunction) {
	fieldExpression = convertFunction.field();
	}
	return fieldExpression instanceof FieldAttribute fieldAttribute ? fieldAttribute : null;
	}

[ES|QL] Add MATCH_PHRASE #127661

Are you sure you want to change the base?

[ES|QL] Add MATCH_PHRASE #127661

Conversation

kderusso commented May 2, 2025 • edited Loading

elasticsearchmachine commented May 7, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elasticsearchmachine commented May 9, 2025

elasticsearchmachine commented May 9, 2025

elasticsearchmachine commented May 9, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ioanatia left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kderusso commented May 2, 2025 •

edited

Loading